home *** CD-ROM | disk | FTP | other *** search
/ Workbench Design / WB Collection.iso / workbench werkzeuge / kickstart tools / makekick / mkick.doc < prev    next >
Text File  |  1996-04-07  |  20KB  |  448 lines
  1.  
  2.                                   MKick 1.6
  3.  
  4.                      (c) 1992-1994 MJSoft System Software
  5.  
  6.                                  Martin Mares
  7.  
  8. ==============================================================================
  9.  
  10.  
  11. Introduction:
  12. -------------
  13.  
  14.    MKick is a replacement of KickIt, ZKick and LKick kickers for use on
  15. machines with kickstart 1.2 or 1.3 in ROM (It also tries to be as powerful
  16. as SinSoft's SKick).
  17.  
  18.    The main advantages of MKick are:
  19.  
  20.  - ability to relocate any kickstart to CHIP, FAST (C0-RAM), NON-AUTOCONFIG
  21.    RAM or EXPANSION RAM if a relocation table is supplied.
  22.  
  23.  - standard operation (like ZKick) if the relocation table is not available.
  24.  
  25.  - reading of both KickIt and ROM Image kickstart formats (encrypted
  26.    beta-ROMs for A600 must be converted by MakeKick)
  27.  
  28.  - patch function using supplied patch file (may correct known kickstart bugs).
  29.  
  30.  - can be started from both the command line and the Workbench.
  31.  
  32.  - Graphic User Interface (GUI).
  33.  
  34.  - Small code size, because it's written completely in assembly.
  35.  
  36.  - loaded kickstart survives user reset and crashes (when the ExecBase is not
  37.    destroyed).
  38.  
  39.  - C0-RAM salvage: many kickstarts perform destructive tests of C0-RAM (FAST
  40.    RAM). MKick stores critical bytes in its own storage and restores their
  41.    contents after memory tests.
  42.  
  43.  - If you have kickstart 39.106 or higher, the alert timing constant
  44.    (execbase+$20E) won't be lost during reboot.
  45.  
  46.  - Non-autoconfig can be added automatically without using special resident
  47.    utilities.
  48.  
  49.  - ROM Kickstart can be relocated to RAM. This speeds up system operation on
  50.    the most of accelerated systems (e.g. GVP A530 Turbo). In this case, you
  51.    needn't the kickstart image file, MKick will load it directly from your ROM.
  52.  
  53.  - Waits for all disks to be validated before performing any operation.
  54.  
  55. New in V1.6:
  56.  
  57.  - New memlist named Kickstart is created if the KS image is not stored in
  58.    one of of original memlists. This prevents MonAm from treating KS image
  59.    as out-of-memory space.
  60.  
  61.  - Ability to get rid of resident modules by simply pressing the left mouse
  62.    button at correct time (see below).
  63.  
  64.  - The .RTB files are no longer distributed in this archive, because I have
  65.    never heard about anyone trying to modify the kickstart headers. If you
  66.    need the RTB to recompile the kickstart header for patch inclusion, you can:
  67.       (1) Download the latest version of SKick archive, which contains the
  68.           RTB files.
  69.       (2) Extract the RTBL chunk from the .kick file. (Extract only chunk body,
  70.           not the header!)
  71.       (3) Ask me.
  72.  
  73.  
  74. Copyright:
  75. ----------
  76.  
  77.   MKick, its documentation and all the utilites (MakeKick, MakeKickDisk and
  78. SwitchScript) are Copyright (C) MJSoft System Software 1994, Prague, Czech
  79. Republic.
  80.  
  81.   This archive may be freely redistributed, but only in original unmodified
  82. state. No files can be added, modified, removed etc. All copyright notices in
  83. the programs and accompanying documentation files must remain on their places.
  84. Also '.displayme' and other similar files may not be added.
  85.  
  86.  
  87. Contents of the archive:
  88. ------------------------
  89.  
  90.    MKick              - executable code of the program
  91.    MKick.info         - icon
  92.    MKick.doc          - this file
  93.    History            - history of development
  94.    MakeKick           - utility for making of kickstart header files
  95.    MakeKick.doc       - its documentation
  96.    MakeKickDisk       - utility for making of kickstart disks with track-loader
  97.    MakeKickDisk.doc   - its documentation
  98.    README.3.1         - some information on 3.1 kickstarts
  99.    SwitchScript       - utility for easy switching of startup scripts
  100.    SwitchScript.doc   - its documentation
  101.    SumKick            - utility for calculating the kickstart image checksum
  102.    SumKick.doc        - its documentation
  103.  
  104.    KSHD/*.kick        - kickstart headers for various kickstarts
  105.    KSHD/*.kshd        - source files for kickstart headers
  106.  
  107.    Delta/*            - delta files to recover patched kickstarts
  108.                         (see delta/README for more info)
  109.  
  110. Included kickstart headers:
  111. ---------------------------
  112.  
  113.    The  kickstart  header  files containing the relocation table and information
  114. needed  to load the kickstart are supplied for following kickstarts:
  115.  
  116.    kick37175.A500            standard 2.04 for A500+
  117.    kick39046.A500.BETA       beta-version of 3.0         (*)
  118.    kick39106.A1200           standard 3.0 for A1200
  119.    kick39110.A500.BETA       beta-version of 3.0         (*)
  120.    kick39115.A3000.BETA      beta-version of 3.0         (*)
  121.    kick39115.A3000SK.BETA    beta-version of 3.0, SuperKickstart file (*)
  122.    kick40003.A3000.BETA      beta-version of 3.0, SuperKickstart file (*)
  123.    kick40038.A600.BETA       beta-version of 3.1     (*)
  124.    kick40068.A600            final version of 3.1
  125.  
  126. (*)- Available only to official developers.
  127.  
  128.    For 3.1 kickstarts, see notes in README.3.1.
  129.  
  130.    If you have a kickstart which is not included in this list, try to download
  131. latest version of SKick if it contains RTB and PAT files for your kickstart
  132. and convert them by the MakeKick utility (AUTO option).
  133.  
  134.  
  135. System requirements:
  136. --------------------
  137.  
  138.   - Amiga 500, 1000 or 2000
  139.  
  140.   - Minimally 1 meg of RAM (all possible combinations)
  141.  
  142.   - Kickstart 1.2 or 1.3 in ROM
  143.  
  144.   - arp.library in the LIBS: directory
  145.  
  146.  
  147. Installation:
  148. -------------
  149.  
  150.    The kickstart images are normally stored in directory DEVS:Kickstarts.
  151. The kickstart header files are stored on the same place.  This directory is
  152. searched automatically in the GUI mode and can be overriden by the KICKDIR
  153. option (see below).
  154.  
  155.    To install MKick, copy the MKick executable (with its icon) into any place
  156. where you wish to have it, create the DEVS:Kickstarts directory and copy
  157. header files for all your kickstarts to it.  Then copy the kickstart images
  158. itself and rename them to names of header files, but without any extension
  159. (it's also possible to rename the header files according to kickstart image).
  160. All the files of one particular kickstart must have identical names (except
  161. extensions).
  162.  
  163.    Note:  There are no kickstart images in this archive.
  164.  
  165.    For best operation, you should insert calling of MKick as the first line of
  166. your Startup-sequence.  It allows MKick to handle all operations requiring
  167. system reboot (switching from one kickstart in RAM to another one etc.)
  168. automatically.  When you hold down the left mouse button during system reboot,
  169. the GUI screen will appear.
  170.  
  171.  
  172. MKick usage:
  173. ------------
  174.  
  175.    MKick may be called either from the CLI or from the Workbench.
  176.  
  177.  
  178. Invocation from the CLI
  179. -----------------------
  180.  
  181.    Syntax: MKick [<kickstart>] [<memory options>] [<other options>]
  182.                  [<debug options>]
  183.  
  184. Kickstart specification:
  185.  
  186.    These parameters specify which kickstart do you want to use:
  187.  
  188.        <name> - install kickstart specified by its name
  189.           GUI - show GUI allowing to select the kickstart and some basic
  190.                 options by the mouse (or the rat if you have one :-)
  191.           ROM - go back to ROM kickstart
  192.  
  193. Memory options:
  194.  
  195.    These options control the place you want to store the kickstart on:
  196.  
  197.         NOREL - load kickstart to its original memory location. Used automati-
  198.                 cally when you have no relocation table for the kickstart.
  199.                 But only few kickstarts are on such locations where you have
  200.                 some RAM. (Many kickstarts are stored in standard ROM memory
  201.                 (at F80000 and higher). Only the beta-ROMs are located at
  202.                 200000 (standard expansion memory) sometimes.)
  203.  
  204. ADR <address> - load kickstart at specified address. It's used mostly for
  205.                 debugging or when kicking to RAM placed on unusual location.
  206.                 The address is specified in hexadecimal (base-16) notation.
  207.                 All addresses of type 00xx0000 (xx is any number) can be
  208.                 written in short form: xx (this is the notation introduced
  209.                 in SKick). The kickstart address must be a multiple of 64K
  210.                 (the last four digits _MUST_ be 0) and mustn't be less than
  211.                 40000.
  212.  
  213. CHIP,FAST,EXP,NAC - load kickstart to CHIP/FAST/EXPANSION/NON-AUTOCONFIG MEMORY.
  214.                 These options may be combined (you can say MKick kick34005.a500
  215.                 CHIP FAST) and MKick will automatically select the best possible
  216.                 location. (The standard order is NAC/EXP/FAST/CHIP, from top
  217.                 to bottom. It is based on standard priority scheme used by Exec.
  218.                 See also ADDMEM.) These options affect memory types offered
  219.                 by the GUI.
  220.  
  221.     <nothing> - When you specify no memory control options, MKick will assume
  222.                 that CHIP, FAST, EXP and NAC options are set.
  223.  
  224. ADDMEM <base> <size> [<priority>] - add a region of NON-AUTOCONFIG RAM to the
  225.                 system. The non-autoconfig (NAC) RAM can be found on many
  226.                 accelerated systems. The basic property of this type of memory
  227.                 is that it's present when the machine is rebooted, but no part
  228.                 of the operating system is able to find it and give it to all
  229.                 application programs. The manufacturers usually supply some
  230.                 utility which is able to do the memory adding for you, but these
  231.                 utilities have significant problems with the most of kickers.
  232.                 In this case, you can simply say MKick where is your memory
  233.                 located, how large is it (specified in bytes; both the address
  234.                 and the size are hexadecimal numbers; the shortened form used
  235.                 by ADR can be used here, too). The priority is a decimal number
  236.                 in range <-128;127>. All regions of available memory are sorted
  237.                 by their priority (expansion memory has 10, fast RAM 0, chip RAM
  238.                 -10, default for ADDMEM is 20). When a program tries to allocate
  239.                 some memory, the Exec will use available memory chunk with the
  240.                 highest priority it founds and because the NAC RAM is often the
  241.                 fastest one in the system, it's very good to use it first.
  242.  
  243. Other options:
  244.  
  245.          AUTO - exit if already kicked. The operation you have selected won't be
  246.                 done if there is already some kickstart in RAM or if you sele-
  247.                 cted (by the ROM option or by the GUI) that you want to use ROM
  248.                 kickstart. For example: if you have MKick in your startup-sequence
  249.                 and you want to start KS 3.0 when you boot first time, you can
  250.                 say 'MKick DEVS:Kickstarts/Kick39106.A1200 AUTO' in this case.
  251.                 It will prevent MKick from trying to re-kick whenever you boot
  252.                 and will allow you to stay in ROM KS without changing anything.
  253.                 you can also say 'MKick AUTO GUI' - it displays GUI only when
  254.                 you didn't select any kickstart before.
  255.  
  256.        NOTAGS - remove all resident modules before kicking. MKick tries to use
  257.                 smart algorithm of removing of modules, which could cause system
  258.                 crash, but there could be an exception that isn't capable of
  259.                 being handled by this way. If MKick doesn't work on your system,
  260.                 try to use this option.
  261.  
  262.       NOPATCH - don't use the patches. The patch tables are usually built to
  263.                 fix known kickstart bugs. Some of these bugs can cause wrong
  264.                 operation of kickers. Don't use this option when you don't know
  265.                 what are you really doing.
  266.  
  267.   KICKDIR <x> - search for kickstarts in specified directory. The default is
  268.                 "DEVS:Kickstarts". It affects only the GUI.
  269.  
  270.         CACHE - turn on CPU caches as soon as it's possible. The machines
  271.                 equipped with 68020 or higher CPU have a CACHE MEMORY. When
  272.                 it's used, it speeds up a bit all operations, but not all
  273.                 programs are compatible with this CPU enhancement. The caches
  274.                 are normally switched on by CPU, SETCPU or other similar
  275.                 command, which can be started from the startup-sequence.
  276.                 If you want to enable the caches automatically, you should
  277.                 specify this option.
  278.  
  279. Debug options:
  280.  
  281.          WAIT - wait for RETURN key before resetting the machine. If you enter
  282.                 'q', MKick will stop the action and exit immediately without
  283.                 deallocating any memory, therefore you can look at MKick's
  284.                 resident module and similar things. If you see that something
  285.                 is wrong, you can press CTRL-C (MKick checks CTRL-C before it
  286.                 installs the resident tags and before each reboot). In this
  287.                 case, MKick deallocates all used memory and terminates. The
  288.                 checking of CTRL-C doesn't depend on WAITing.
  289.  
  290.         DEBUG - turn on debugging information. It consists of two sequences
  291.                 of colourful stripes displayed during reboot with RAM KS.
  292.                 The first set of stripes (all colours) is displayed before
  293.                 the RAM KS is started. The second (black & white) one is
  294.                 displayed when MKick fixes RAM, adds autoconfig devices
  295.                 and does many other things. During the second phase, if you
  296.                 hold the left mouse button and you have KS V36 or higher, the
  297.                 startup-sequence will be disabled (the mouse button is tested
  298.                 immediately after the black & white stripes appear). Please
  299.                 include effect of this option if you are preparing a bug
  300.                 report for me. Warning: pressing of LMB during the first phase
  301.                 has different effect - removing of all resident modules.
  302.  
  303.        NOTEST - don't test kickstart image before using it. Don't use, because
  304.                 invalid kickstart images don't work properly.
  305.  
  306.         FORCE - don't fail if kickstart memory can't be allocated. Used rarely,
  307.                 but if you have some non-autoconfig memory at $600000 and you
  308.                 don't want to use ADDMEM and the memory is not added to the
  309.                 system, you should enter 'MKick <kickstart name> ADR 60 FORCE'.
  310.  
  311.  
  312. Invocation from Workbench:
  313. --------------------------
  314.  
  315.    Simply double-click on MKick's icon and MKick will be started.  Using
  316. 'Info' or 'Information' (WB 2.0 or higher), you may specify all previously
  317. mentioned options using the tool types.  The boolean (ON/OFF) switches can be
  318. enabled using their name followed by '=' or '=ON'.  If the kickstart name
  319. (FILE=) is not specified, the GUI is started automatically.
  320.  
  321.  
  322. Graphic User Interface:
  323. -----------------------
  324.  
  325.    When MKick is started in the GUI mode, a screen with a list of available
  326. kickstarts will appear.  You may select the kickstart you want to use or hit
  327. 'Cancel'.
  328.  
  329.    Then you may select the type of RAM you want to store the kickstart to
  330. (ORIGINAL location, CHIP RAM, FAST RAM, EXP RAM, NAC RAM or ANY RAM if you
  331. want to choose the optimal location automatically).  It's also possible to
  332. disable the patches.  Then hit the 'OK' gadget to start the whole loading
  333. process.
  334.  
  335.  
  336. Types of operations:
  337. --------------------
  338.  
  339.  - Normal loading - used when you load the kickstart to memory which is free
  340.  
  341.  - Loading to temporary buffer - used when you want to load the kickstart to
  342. memory which is not free, but if there is some room to load the image to.
  343.  
  344.  - Hard loading - used if the FORCE option has been specified. In this case,
  345. the RAM block containing the kickstart image will be allocated only if it's
  346. possible. Unsuccessful allocation will not be reported.
  347.  
  348.  - Disconnecting of C0-RAM - used if you have only 0.5M of CHIP RAM and 0.5M
  349. of FAST RAM.  MKick will perform a reset to disconnect the FAST RAM from the
  350. system memory list.  Then (if started again) it will load the kickstart to the
  351. disconnected C0-RAM.
  352.  
  353.  - Loading from kickstart disk - MKick allows to load the kickstart from the
  354. floppy. It supports original SuperKickstart disks for the A3000 and the
  355. specially formatted disks created by MakeKickDisk.
  356.  
  357.  - Removing of RAM kickstart - uses reset
  358.  
  359.  - Replacing RAM kickstart by another RAM kickstart - uses reset to remove the
  360. old one and then (if started again, normally from the Startup-sequence) tries
  361. to load the kickstart using one of previously mentioned methods.
  362.  
  363.  
  364. Common problems:
  365. ----------------
  366.  
  367.  - MKick has no effect - normal reboot happens: Some resident modules collide
  368. with MKick. MKick normally tries to remove such modules, but ... you can fix
  369. it by using of the NOTAGS option or by removing the module manually.
  370.  
  371.  - Colourful stripes move on the screen and the machine seems to be crashed:
  372. It occurs when MKick isn't able to allocate the kickstart block memory. Try
  373. the operation again after a cold reboot.
  374.  
  375.  - Black and white stripes and the machine seems to be crashed: Kickstart image
  376. checksum error during AUTOSUM test. Some program has destroyed the kickstart.
  377. Use MKick again.
  378.  
  379.  - Black and white stripes, which disappear if you press the left mouse button:
  380. MKick is unable to allocate space for some resident module. This should not
  381. happen, but when it happens, it can be fixed if you select the NOTAGS switch.
  382.  
  383.  - Quickly blinking power led with red color of screen background: Kickstart
  384. image checksum doesn't match. Some program has destroyed the kickstart. Use
  385. MKick again.
  386.  
  387.  - "Incorrect or suspicious kickstart file" message: the kickstart file you
  388. have supplied is corrupted or encrypted. The only thing you can do with
  389. corrupted kickstart files is to throw them out. The encrypted files can be
  390. decrypted using the MakeKick utility (see the KICKTO option of MakeKick).
  391.  
  392.  - "Incorrect kickstart address in header file","Invalid kickstart original
  393. address","Corrupted kickstart file","Kickstart file doesn't match the header",
  394. "Error reading kickstart file" and other similar messages: The kickstart file
  395. you have supplied doesn't match the kickstart header. Your kickstart can be
  396. corrupted or patched, but there's also a possibility that you have choosed
  397. wrong name of the kickstart.
  398.  
  399.   - MKick can crash if you use some ROM remapping utility.
  400.  
  401.  
  402. Removing of resident modules:
  403. -----------------------------
  404.  
  405.    In several situations, you might want to remove all resident modules
  406. which survive reset (such as RAD, NewAlertHook etc. - especially useful
  407. if debugging such a thing). MKick can help you: If you hold the left mouse
  408. button during system reboot (after initialization of ROM kickstart, but before
  409. start of RAM one), the resident modules except MKick's own module are removed.
  410.  
  411.    Warning: If you want to invoke bootmenu, you must press the buttons
  412. after the RAM kickstart is started to avoid the actions described above.
  413.  
  414.  
  415. Thanks:
  416. -------
  417.  
  418.  - to Commodore-Amiga for the Operating System.
  419.  
  420.  - to SinSoft for his SKick and a lot of good ideas.
  421.  
  422.  - to Tomas Zikmund, Petr Cisar and Stefan Stuntz for beta-testing.
  423.  
  424.  - ... (for ...?)
  425.  
  426.  
  427. Final words:
  428. ------------
  429.  
  430.    This program, its documentation and all other files contained in this
  431. archive, are (c) Copyright Martin Mares, Kankovskeho 1241, 182 00 Praha 8,
  432. Czech Republic.  This package is provided as is, any warranties cannot be
  433. applied.  Any usage of this program or other parts of this archive will be
  434. done at your own risk!
  435.  
  436.    Known bugs: MKick probably doesn't work with 68040 CPU, because I have no
  437.                beta-testers with such machine and I have no documentation for
  438.                this CPU.
  439.  
  440.    Send bug reports and comments to mjsoft@k332.feld.cvut.cz
  441.     (When sending a bug report, you should describe what happens,
  442.      including effect of the NOTAGS, DEBUG and NOTEST options. Also try
  443.      to detect any dependence on memory you have the kickstart stored in
  444.      (use FAST, CHIP, EXP options) and don't forget to specify your
  445.      hardware configuration.)
  446.  
  447.    Excuse me for my bad English and all bugs.
  448.